/*
*  Copyright (c) 2001 Sun Microsystems, Inc.  All rights
*  reserved.
*
*  Redistribution and use in source and binary forms, with or without
*  modification, are permitted provided that the following conditions
*  are met:
*
*  1. Redistributions of source code must retain the above copyright
*  notice, this list of conditions and the following disclaimer.
*
*  2. Redistributions in binary form must reproduce the above copyright
*  notice, this list of conditions and the following disclaimer in
*  the documentation and/or other materials provided with the
*  distribution.
*
*  3. The end-user documentation included with the redistribution,
*  if any, must include the following acknowledgment:
*  "This product includes software developed by the
*  Sun Microsystems, Inc. for Project JXTA."
*  Alternately, this acknowledgment may appear in the software itself,
*  if and wherever such third-party acknowledgments normally appear.
*
*  4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA"
*  must not be used to endorse or promote products derived from this
*  software without prior written permission. For written
*  permission, please contact Project JXTA at http://www.jxta.org.
*
*  5. Products derived from this software may not be called "JXTA",
*  nor may "JXTA" appear in their name, without prior written
*  permission of Sun.
*
*  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
*  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
*  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
*  DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
*  ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
*  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
*  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
*  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
*  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
*  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
*  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
*  SUCH DAMAGE.
*  ====================================================================
*
*  This software consists of voluntary contributions made by many
*  individuals on behalf of Project JXTA.  For more
*  information on Project JXTA, please see
*  <http://www.jxta.org/>.
*
*  This license is based on the BSD license adopted by the Apache Foundation.
*
*  $Id: Plugin.java,v 1.3 2005/10/05 19:21:23 nano Exp $
*/

package net.jxta.myjxta.plugin;


/**
 *
 * This is the interface that each myjxta plugin must implement
 *
 * The lifecycle:
 * 1. a blank constructor of the plugin class is instantiated (at myjxta startup)
 * 2. init is called to tell the plugin who is his container (at myjxta startup)
 * 3. start (maybe/is) called to tell the plugin that the user has activated the corresponding
 *    plugin action in the main menu
 * 4. stop (maybe/is) called to tell the plugin that the user has deactivated the
 *    corresponding plugin menu
 * 5. destroy is called to tell the plugin that it will be unloaded (myjxta shutdown / plugin is unloaded/reloaded)
 * @version $Id: Plugin.java,v 1.3 2005/10/05 19:21:23 nano Exp $
 *
 * @author frank toennies
 */

public interface Plugin {


    /**
     * init the plugin - this method is run inside the main application thread
     * dont do anything lenghly here
     * @param c - The plugincontainer this plugin runs in
     */
    public void init(PluginContainer c);

    /**
     * the user has activated the corresponding plugin checkbox
     * --> start your actual work here
     * This method is called from a peer plugin separate thread
     * Your last step should be to ensure that isRunning returns true if you sucessfully started the plugin
     */
    public void start();

    /**
     * The user has deactivated the corresponding plugin checkbox --> stop what you are doing
     * and save your data (called in a separate thread for each plugin)
     * Your last step should be to ensure that isRunning() returns false (if you
     * stopped sucessefully)
     */
    public void stop();


    /**
     * Last step in the plugin livecycle - this is your last chance to save
     * your data
     */
    public void destroy();

    /**
     * is this plugin currently running (started and running)?
     * @return true if the plugin is running and working - false in all other cases
     *         if a plugin returns <code>false</code> it can be started - if a plugin
     *         returns true it can be stopped.
     */
    public boolean isRunning();

    /**
     * The PluginNotificationHandler is used to communicate with the plugin and inform
     * it about ongoing events in the mainapp
     * @return the handler that the container will use to inform the plugin
     */
    IPluginNotificationHandler getPluginNotificationHander();

    /**
     * The Name of the plugin - right now this will be used for the mainmenu entry only
     * @return
     */
    String getName();


}
